
___________________

GreyEdit user guide
___________________


User, please note
=================

GreyEdit is Freeware, i.e. it is free software, but not public domain.

Copyright notice
================

The copyrights (c) of this program belong to John Kortink. All rights are
reserved.

You may not make changes to this program (except for documented configuration
changes). If you distribute it, you may only distribute the complete and
unchanged original copy (as you first received it). You may distribute this
program freely, but must obtain written permission from me if it is to be
distributed as part of, or alongside, any product that is meant to generate
profits. This program is provided 'as is'. Fitness of this program for any
particular purpose is not implied. Using it is entirely at your own risk.


//
//
// Introduction
//
//

Features :

- Can read (greyscale) Clear format files.

- Can write (greyscale) Clear and Sprite format files.

- Can perform a variety of processing functions : crop, filter (e.g. blur,
  sharpen, noise), range expansion, equalization, invert, simple pixel editing
  (e.g. to remove noise pixels by hand).

- Serves as a frontend for, and can grab video images via, the Zeridajh video
  digitiser podule, if fitted (only a small number of these podules were sold,
  but the hardware design was eventually published in several international
  issues of Elektor in 1991).

Note that GreyEdit offers only limited editing functionality, handles only a
single, greyscale image at a time, and offers very limited import and export
functions. If you require more powerful functionality in any of these respects,
you may want to try my Shareware application Translator instead. GreyEdit is,
basically, still 'around' because it is a simple, 'lean and mean' application,
and also very effective as a front end for the Zeridajh video digitiser.


//
//
// Compatibility
//
//

GreyEdit should be compatible with :

- RISC OS 3.1 and later
- ARM 2 and later processors (26-bit architectures only)


//
//
// Using GreyEdit
//
//

Start !GreyEdit. Click MENU on GreyEdit's iconbar icon.

GreyEdit's iconbar menu pops up, showing the following entries :

- 'Info' and 'Quit' require no explanation.
- 'Choices' gives access to the 'Choices' menu.
- 'Create' gives access to the 'Create' menu.
- 'Other' gives access to the 'Other' menu.
- Clicking 'Options ...' opens the 'Options' window.

The menus and window mentioned are discussed in detail below.


//
//
// The 'Create' menu
//
//

Via this menu images can be created :

- To create a blank image follow 'Blank image', enter the required resolution,
  and click 'Blank image'.

(If the Zeridajh video digitiser is present :)

- To digitise a plain greyscale image, click 'Grab grey'.

- To digitise a colour image instead (this is only possible if the colour
  extension is fitted), follow 'Grab colour', enter a leaf name, and drag the
  directory icon to a Filer window. A red, green and blue image will be
  grabbed, and saved in the chosen directory as greyscale Clear files named
  'R', 'G' and 'B'. If needed, the three files can subsequently be merged to a
  colour Clear file by dragging the directory containing them to the GreyEdit
  iconbar icon. Enter a leaf name, and drag the Clear file icon to a Filer
  window.

When the image has been created, the Image window pops up, showing the new (or
last, i.e. 'blue') image. Clicking MENU on the Image window pops up the Image
menu. The Image menu is discussed in detail below.


//
//
// The Image menu
//
//

This menu contains the following entries :

- 'Image info' leads to an information window showing details about the image.

- 'Pixel info' leads to an information window showing the (edge relative)
  coordinates of the image pixel currently under the pointer (see 'Edit').

- 'Pattern' leads to a control window that offers pattern generating functions.
  Enter a value between 0 and 255 and click 'Fill' to fill the image with the
  chosen greyvalue. Click on one of the pattern icons to fill the image with
  the indicated pattern, from left to right : horizontal, vertical or diagonal
  lines of increasing greyvalue (0..255 from top to bottom, left to right or
  top left to bottom right respectively), or random greyvalues. Note that the
  order of the greyvalues can be reversed, if needed, by subsequent execution
  of 'Process -> Invert' (see 'Processing functions').

- 'Process' leads to image processing functions (all of them affect the entire
  image). Refer to 'Processing functions' for details.

- 'Zoom' leads to a control window offering an image zoom function. Either
  enter the zoom factors and click on the button in the middle, or click the
  'arrows' for an instant effect (incrementing or decrementing the relevant
  factor).

- 'Save' leads to the Clear file and Sprite file save windows. Save the current
  image by entering a leaf name and dragging the icon to a Filer window.

- Click 'Edit' to enable/disable editing. If editing is enabled (i.e. 'Edit' is
  ticked), image pixels may be edited by hand (useful to remove noise pixels
  from a digitised image) and/or the image may be cropped. Click SELECT on a
  pixel to assign the average greyvalue of the eight neighboring pixels, or
  ADJUST to include the pixel itself as well (the latter is equivalent to the
  result of the 'Average' filter, refer to 'Processing functions' for details).
  Pressing SHIFT, click SELECT to crop the image so that the pixel clicked on
  becomes the new top left pixel of the image, or ADJUST so that it becomes the
  new bottom right pixel of the image. While editing is enabled, the 'body' of
  pointer continuously reflects the greyvalue of the pixel 'under' it.

Note that all windows mentioned can be made 'permanent' (so they can be used
more easily, especially the Zoom and Pattern windows) by clicking on the menu
item leading to the window.

Saved sprite files are 'special' in that they contain the image as it would be
displayed in 256 colour modes. In 256 colour modes, greyvalues are mapped to
colours in such a way that 'turning the colour off' (i.e. switching the monitor
to monochrome) would provide a reasonably decent result. This trick is useful
when running GreyEdit on pre Risc PC machines, since these do not offer '256
greys' modes. It is advisable to load and save only Clear files (if you can)
and to always use '256 greys' (or '16 million colours') modes (if available).


//
//
// Processing functions
//
//

=====================
- Process -> Filter =
=====================

This leads to a submenu containing 'filter' functions. A filter function looks
at every pixel in turn, and recalculates its value, considering the old value
of the pixel and the values of every one of its eight neighbor pixels (i.e.
the pixels to the 'north', 'south', 'east', 'west', 'north-east', 'north-west',
'south-east' and 'south-west'). An alternative way of looking at this is by
imagining a 3x3 pixel window moving over the original image, in which the
middle pixel's value is replaced by the result of a calculation involving the
values of all the nine pixels in the window (replacing, however, does not occur
until the calculations have been performed for all image pixels).

Note that some 'neighbors' of pixels at the edge of the image are not available
(for example, the top left pixel has only 'east', 'south' and 'south-east'
neighbors). In these cases, any missing neighbor pixel is assumed to have the
value of the (in position) nearest image pixel.

Most filters take the pixels in the 3x3 pixel window, multiply their values by
a factor which is different depending on the position of the pixel in the 3x3
pixel window, and accumulate the resulting values. This value is subsequently
divided by the total of the multiplication factors, yielding the new pixel
value. The set of multipliers is usually referred to as a 'kernel'.

=============================
= Process -> Filter -> Blur =
=============================

These filters all have a 'blurring' effect.

Kernels of blurring filters generally consist entirely of positive factors.
This has an 'averaging' effect (the new pixel value is the 'weighted average'
of the values of the pixels in the pixel window).

========================================
= Process -> Filter -> Blur -> Average =
========================================

This uses a kernel of :

 1 1 1
 1 1 1
 1 1 1

======================================
= Process -> Filter -> Blur -> Gauss =
======================================

This uses a kernel of :

 1 2 1
 2 4 2
 1 2 1

================================
= Process -> Filter -> Sharpen =
================================

These filters all have a 'sharpening' effect.

Kernels of sharpening filters generally consist entirely of negative factors,
except for the middle factor, which is positive. The factors must add up to a
total of 1 or higher.

================================================
= Process -> Filter -> Sharpen -> Sharpen weak =
================================================

This uses a kernel of :

 -1 -1 -1
 -1 24 -1
 -1 -1 -1

==================================================
= Process -> Filter -> Sharpen -> Sharpen strong =
==================================================

This uses a kernel of :

 -1 -1 -1
 -1 16 -1
 -1 -1 -1

===========================================
= Process -> Filter -> Sharpen -> Laplace =
===========================================

This uses a kernel of :

  0 -1  0
 -1  5 -1
  0 -1  0

=======================================
= Process -> Filter -> Sharpen -> Lee =
=======================================

This does not use a kernel but a formula :

'The new value is the maximum value in the window or the minimum value in the
window, whichever differs least from the value of the middle'.

==============================
= Process -> Filter -> Noise =
==============================

These filters all have a 'noise removal' effect. They don't use kernels.

============================================
= Process -> Filter -> Noise -> Noise weak =
============================================

This does not use a kernel but a formula :

'If and only if west is equal to east, then the new value is west'.

==============================================
= Process -> Filter -> Noise -> Noise strong =
==============================================

This does not use a kernel but a formula :

'If and only if the maximum of north, west, middle, east and south is equal to
the middle (and only the middle), or the minimum of north, west, middle, east
and south is equal to the middle (and only the middle), then the new value is
the average of north, west, east and south'.

==============================
= Process -> Filter -> Other =
==============================

These filters are useful for 'effects'.

=========================================
= Process -> Filter -> Other -> Maximum =
=========================================

This does not use a kernel but a formula :

'The new value is the maximum value in the window'.

=========================================
= Process -> Filter -> Other -> Minimum =
=========================================

This does not use a kernel but a formula :

'The new value is the minimum value in the window'.

==========================================
= Process -> Filter -> Other -> Sobel X+ =
==========================================

This uses a kernel of :

 -1 0 1
 -2 0 2
 -1 0 1

Note that 127 is added to the accumulated value before division because the
total multiplication factor is 0.

==========================================
= Process -> Filter -> Other -> Sobel X- =
==========================================

This uses a kernel of :

 1 0 -1
 2 0 -2
 1 0 -1

Comments as for 'Sobel X+'.

==========================================
= Process -> Filter -> Other -> Sobel Y+ =
==========================================

This uses a kernel of :

 -1 -2 -1
  0  0  0
  1  2  1

Comments as for 'Sobel X+'.

==========================================
= Process -> Filter -> Other -> Sobel Y- =
==========================================

This uses a kernel of :

  1  2  1
  0  0  0
 -1 -2 -1

Comments as for 'Sobel X+'.

===========================
= Process -> Expand range =
===========================

Clicking on this menu entry will improve the contrast of the image.

This function determines the range of intensity values used in the image and,
if possible, remaps the intensity values to maximize that range.

=======================
= Process -> Equalize =
=======================

Clicking on this menu entry will perform 'histogram equalization' on the image.

Histogram equalization measures the accumulated frequencies of all intensity
values used in the image. The intensity values are subsequently remapped so
that the new frequency graph more closely resembles a straight line.

Note that histogram equalization does not necessarily improve an image's
quality. The effect depends greatly on the image contents.

=====================
= Process -> Invert =
=====================

Clicking on this menu entry will 'invert' the image.

The result is a 'negative' image (i.e. inverting twice results in the original
image).


//
//
// The 'Other' menu
//
//

This menu contains the following entries :

- Clicking 'Grey desktop' in 16 colour modes changes the palette to '16 greys'.
  This is only useful on pre Risc PC machines (i.e. machines that don't offer
  '256 greys' modes).

- Clicking 'Colour desktop' in 16 colour modes changes the palette (back) to
  '16 colours'.

(If the Zeridajh video digitiser is present :)

- Clicking 'Video signal ...' will capture video timing signals and (re-)open
  the Video Signal window to display them. Two 'traces' are drawn. The top one
  shows the colour burst ('up' is burst, 'down' is NOT burst) and vsync signals
  (green is NOT vsync, red is vsync). The bottom one shows the odd/even frame
  signal (cyan indicates even, black odd). At the bottom of the Video Signal
  window a quick 'analysis' is shown : 'Normal video signal' and 'No video
  signal' are both self-explanatory, 'MacroVision protected video tape signal'
  is shown if MacroVision-like pulses have been detected in the vsync period.


//
//
// The 'Options' window
//
//

You will find two sections in this window, 'Digitiser' and 'Miscellaneous'.

The 'Digitiser' section provides a few Zeridajh video digitiser controls. Use
the 'Sensitivity' control (available if the sensitivity extension is fitted) to
change the video signal amplitude corresponding to the maximum greyvalue. Enter
a value in the writable field below 'Line skip' (0 defaults to 20) to select
the number of video lines to skip at the top of every video frame. Change the
resolution of the image grabbed under 'Image size'. Switch to a different input
(only if the colour extension is fitted) under 'Input switch'.

In the 'Miscellaneous' section, the 'Auto grey desktop' option can be switched
on or off. When on, a 'Grey desktop' (refer to 'The Other menu' for details) is
performed automatically after every mode change.


//
//
// The 'Choices' menu
//
//

In this menu you can manipulate GreyEdit's 'choices'.

- 'Save' will save the current choices.
- 'Load' will load the saved choices.
- 'Default' will load the default choices.
- 'Kill' will discard the saved choices.

When GreyEdit starts up it loads the saved choices, or the default choices if
no choices were saved.

The choices consist of all the settings in the 'Options' window.


//
//
// Epilogue
//
//

Updates of GreyEdit (if any appear) will be made available by (in order of
preference) :

- World Wide Web : visit web.inter.nl.net/users/J.Kortink
- Electronic mail : email kortink@inter.nl.net

Enjoy !


John Kortink



